Creating and Drawing Points (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 2 - Geometric Shapes / Using Geometric Shapes

Creating and Drawing Points
QuickDraw GX provides a number of methods to create and draw geometric shapes. In general, to draw a shape you must first define a geometry. You can then draw the shape in one of two ways:

You can draw the geometry directly--without having to create a shape object.
You can create a shape object to encapsulate the geometry and then draw the shape.

The first sample function in this section, shown in Listing 2-1, uses the first method--it draws a point without creating a point shape.
To draw the point, this sample function first defines a point geometry, which is represented by a point structure (of type gxPoint):
struct gxPoint {
   Fixed    x;
   Fixed    y;
};
The value in the x field specifies horizontal distance from the origin; greater values indicate distances further to the right. The value in the y field specifies vertical distance from the origin; greater values indicate distances further down.

Note
The coordinates of a shape's geometry go through a number of transformations before the shape is actually drawn. Where the shape is drawn depends not only on the values of the shape's geometry, but also on the shape's associated transform and view port objects. If you use the default transform and view port information, the coordinates in a shape's geometry represent units of 1/72 inch and the origin is the upper-left corner of the view port. See Inside Macintosh: QuickDraw GX Objects for more information about the coordinate systems of QuickDraw GX.
Since each coordinate of a point must be a fixed-point value, the sample function in Listing 2-1 uses the GXIntToFixed macro to convert integer constants to fixed-point constants.
The sample function then draws the point using the GXDrawPoint function. The GXDrawPoint function takes a pointer to a gxPoint structure as its only parameter and draws the corresponding point. When drawing the point, it uses the style, ink, and transform information associated with the default point shape.
Listing 2-1 Drawing a point without creating a point shape
void DrawASinglePoint(void)
{
   static gxPoint aPointGeometry = {GXIntToFixed(5),
                                    GXIntToFixed(5)};
   
   GXDrawPoint(&aPointGeometry);
}
QuickDraw GX provides the ff macro as an alias for the GXIntToFixed macro. In the example in Listing 2-1, the point coordinates could be specified with this line of code:
static gxPoint aPointGeometry = {ff(5), ff(5)};
The rest of the examples in "Using Geometric Shapes" use this convenient alternative.
Figure 2-17 shows the result of the sample function from Listing 2-1.
Figure 2-17 A point

Listing 2-1 defines the point at location (5.0, 5.0), which lies at the intersection of two infinitely thin grid lines, and therefore is infinitely thin itself. However, when QuickDraw GX draws this point shape, it draws it as a single pixel--the pixel lying down and to the right of the point itself, as shown in Figure 2-17. QuickDraw GX only draws this single-pixel type of point, called a hairline point, if the pen width property of the style object associated with the point shape has a value of 0, which is the default value for this property. If the pen width is greater than 0.0, QuickDraw GX does not draw the point, unless it has a start cap, in which case only the start cap is drawn. For more information about the pen width property and cap property of style objects and how they affects the drawing of point shapes, see the chapter "Geometric Styles," in this book.
Although you may sometimes want to draw a shape without creating a shape object for it, you will frequently want to create a shape object before drawing a shape. Creating a shape object has many advantages; for example, it allows you to provide custom style, ink, and transform information before drawing the shape.
QuickDraw GX provides three main methods for creating geometric shapes:

You can call a type-specific function, such as GXNewPoint, which requires you to provide a pointer to the shape's desired geometric structure.
You can call the GXNewShapeVector function, which requires you to specify the shape type and provide a pointer to the shape's desired geometric structure.
You can call the GXNewShape function, which requires you to specify the desired shape type, and then call a type-specific function, such as GXSetPoint, to set the geometry.

The sample functions in Listing 2-2, Listing 2-3, and Listing 2-4 show how to create a point shape using these three methods.
Listing 2-2 uses the GXNewPoint function to create a point shape given a pointer to a point geometry.
Listing 2-2 Creating a point shape with the GXNewPoint function
void CreatePointShape(void) 
{
   gxShape      aPointShape;
   static gxPoint aPointGeometry = {ff(5), ff(5)}; 
      
   aPointShape = GXNewPoint(&aPointGeometry);
   
   GXDrawShape(aPointShape);

   GXDisposeShape(aPointShape);
}
Listing 2-3 uses the GXNewShapeVector function to create a point shape. The GXNewShapeVector function requires two parameters:

the shape type of the shape you want to create
an array of fixed-point values that represent the shape's geometry

In this example, the desired shape type is gxPointType and the geometry is specified as an array of two fixed-point values representing the coordinates of the point's geometry. When using the GXNewShapeVector function to create shapes more complicated than point shapes, you need to provide more values in this array.
Listing 2-3 Creating a point shape with the GXNewShapeVector function
void CreatePointShape(void)
{
   gxShape      aPointShape;
   static Fixed aPointGeometry[] = {ff(5), ff(5)};


   aPointShape = GXNewShapeVector(gxPointType, aPointGeometry);

   GXDrawShape(aPointShape);

   GXDisposeShape(aPointShape);
}
Listing 2-4 creates a point shape using the GXNewShape function. The GXNewShape function requires only that you specify the type of shape to create. You do not have to specify any values for the geometric points of the shape's geometry--the GXNewShape function initializes the point geometry to (0.0, 0.0).
To set the values of the point shape's geometry once it's created, the sample function in Listing 2-4 uses the GXSetPoint function. This function takes a reference to the shape and a pointer to the desired geometry as its parameters.
Listing 2-4 Creating a point shape with the GXNewShape and GXSetPoint functions
void CreatePointShape(void)
{
   gxShape  aPointShape;

   static gxPoint aPointGeometry = {ff(5), ff(5)}; 
   
      
   aPointShape = GXNewShape(gxPointType);
   GXSetPoint(aPointShape, &aPointGeometry);
   
   GXDrawShape(aPointShape);

   GXDisposeShape(aPointShape);
}
The sample functions in Listing 2-2, Listing 2-3, and Listing 2-4 all use the GXDrawShape function to draw the point after the point shape has been created. The resulting point is the same for all three examples; it appears as shown in Figure 2-17.
You can use the GXSetPoint function to replace a point shape's geometry any number of times. The sample function in Listing 2-5 creates a point shape, sets its geometry using the GXSetPoint function, draws the point, replaces its geometry using the GXSetPoint function, and draws the point again.
Listing 2-5 Using the GXSetPoint function to replace a point shape's geometry
void ReplacePointShapeGeometry(void)
{
   gxShape  aPointShape;

   static gxPoint aPointGeometry = {ff(5), ff(5)}; 
   static gxPoint anotherPointGeometry = {ff(13), ff(8)}; 
   
      
   aPointShape = GXNewShape(gxPointType);
   GXSetPoint(aPointShape, &aPointGeometry);
   GXDrawShape(aPointShape);

   GXSetPoint(aPointShape, &anotherPointGeometry);
   GXDrawShape(aPointShape);

   GXDisposeShape(aPointShape);
}
Figure 2-18 depicts the results of this sample function.
Figure 2-18 Two different point geometries

Most of the sample functions discussed in "Using Geometric Shapes" create shape objects. If you create a shape object using any of the methods discussed, you are responsible for disposing of the shape when you no longer need it. You can do this using the GXDisposeShape function, which decrements the owner count of the shape and frees the memory occupied by that shape if the shape's owner count becomes 0. The examples of this section dispose of the point shape by calling
GXDisposeShape(aPointShape);
Since the GXNewPoint, GXNewShapeVector, and GXNewShape functions all return a shape with an owner count of 1, calling the GXDisposeShape function in the three previous examples would decrement the owner count to 0 and therefore purge the point shape from memory. For a complete discussion of creating and disposing of shapes, see Inside Macintosh: QuickDraw GX Objects.
For more information about point shapes, see "Point Shapes" on page 2-16 and "The Point Structure" on page 2-104.
For information about the functions you can use to create and draw points, see the description of the GXNewPoint function on page 2-111 and the GXDrawPoint function on page 2-158.